package com.pnnd.stream;

public interface BufAllocator {

    /**
     * Allocate a {@link Buffer}. If it is a direct or heap buffer
     * depends on the actual implementation.
     */
    Buffer buffer();

    /**
     * Allocate a {@link Buffer} with the given initial capacity.
     * If it is a direct or heap buffer depends on the actual implementation.
     */
    Buffer buffer(int initialCapacity);

    /**
     * Allocate a {@link Buffer} with the given initial capacity and the given
     * maximal capacity. If it is a direct or heap buffer depends on the actual
     * implementation.
     */
    Buffer buffer(int initialCapacity, int maxCapacity);

    /**
     * Allocate a {@link Buffer}, preferably a direct buffer which is suitable for I/O.
     */
    Buffer ioBuffer();

    /**
     * Allocate a {@link Buffer}, preferably a direct buffer which is suitable for I/O.
     */
    Buffer ioBuffer(int initialCapacity);

    /**
     * Allocate a {@link Buffer}, preferably a direct buffer which is suitable for I/O.
     */
    Buffer ioBuffer(int initialCapacity, int maxCapacity);

    /**
     * Allocate a heap {@link Buffer}.
     */
    Buffer heapBuffer();

    /**
     * Allocate a heap {@link Buffer} with the given initial capacity.
     */
    Buffer heapBuffer(int initialCapacity);

    /**
     * Allocate a heap {@link Buffer} with the given initial capacity and the given
     * maximal capacity.
     */
    Buffer heapBuffer(int initialCapacity, int maxCapacity);

    /**
     * Allocate a direct {@link Buffer}.
     */
    Buffer directBuffer();

    /**
     * Allocate a direct {@link Buffer} with the given initial capacity.
     */
    Buffer directBuffer(int initialCapacity);

    /**
     * Allocate a direct {@link Buffer} with the given initial capacity and the given
     * maximal capacity.
     */
    Buffer directBuffer(int initialCapacity, int maxCapacity);

    /**
     * Returns {@code true} if direct {@link Buffer}'s are pooled
     */
    boolean isDirectBufferPooled();

    /**
     * Calculate the new capacity of a {@link Buffer} that is used when a {@link Buffer} needs to expand by the
     * {@code minNewCapacity} with {@code maxCapacity} as upper-bound.
     */
    int calculateNewCapacity(int minNewCapacity, int maxCapacity);
}
